자바스크립트 코드 품질 게이트: 프리커밋 훅 구성 마스터하기

끊임없이 진화하는 소프트웨어 개발 세계에서 높은 코드 품질을 유지하는 것은 매우 중요합니다. 깨끗하고, 형식이 잘 갖춰져 있으며, 버그가 없는 코드는 유지보수 비용을 줄일 뿐만 아니라 협업을 촉진하고 개발 주기를 가속화합니다. 코드 품질을 강제하는 강력한 기술 중 하나는 프리커밋 훅을 사용한 코드 품질 게이트의 구현입니다. 이 글에서는 자바스크립트 프로젝트를 위한 프리커밋 훅 구성에 대한 포괄적인 가이드를 제공하여, 코드가 저장소에 도달하기 전에 코드 품질 검사를 자동화할 수 있도록 합니다.

프리커밋 훅이란 무엇인가요?

Git 훅은 commit, push, receive와 같은 이벤트 전후에 Git이 실행하는 스크립트입니다. 프리커밋 훅은, 특히, 커밋이 확정되기 전에 실행됩니다. 이는 커밋되는 변경 사항을 검사하고 미리 정의된 품질 기준을 충족하지 않는 커밋을 방지할 수 있는 중요한 기회를 제공합니다. 낮은 품질의 코드가 코드베이스에 들어오는 것을 막는 문지기라고 생각하면 됩니다.

자바스크립트 코드 품질을 위해 프리커밋 훅을 사용하는 이유는 무엇인가요?

• 조기 오류 감지: 프리커밋 훅은 개발 과정 초기에 코드 품질 문제를 발견하여 더 이상 전파되는 것을 방지합니다. 이는 코드 리뷰 중이나, 더 심하게는 프로덕션 환경에서 문제를 발견하는 것보다 훨씬 효율적입니다.
• 자동화된 코드 포매팅: 팀과 프로젝트 전반에 걸쳐 일관된 코드 스타일을 보장합니다. 자동 포매팅은 스타일 관련 논쟁을 방지하고 더 읽기 쉬운 코드베이스에 기여합니다.
• 코드 리뷰 부담 감소: 코딩 표준을 자동으로 강제함으로써 프리커밋 훅은 코드 리뷰어의 부담을 줄여주어, 그들이 아키텍처 결정과 복잡한 로직에 집중할 수 있게 합니다.
• 코드 유지보수성 향상: 일관되고 고품질인 코드베이스는 시간이 지남에 따라 유지보수하고 발전시키기 더 쉽습니다.
• 일관성 강제: 누가 작성했는지에 관계없이 모든 코드가 프로젝트 표준을 준수하도록 보장합니다. 이는 개인의 코딩 스타일이 다를 수 있는 런던, 도쿄, 부에노스아이레스와 같이 서로 다른 위치에서 근무하는 분산된 팀에서 특히 중요합니다.

자바스크립트 코드 품질을 위한 주요 도구

프리커밋 훅과 함께 자바스크립트 코드 품질 검사를 자동화하기 위해 일반적으로 사용되는 몇 가지 도구가 있습니다:

• ESLint: 잠재적인 오류를 식별하고, 코딩 스타일을 강제하며, 코드 가독성을 향상시키는 데 도움을 주는 강력한 자바스크립트 린터입니다. 광범위한 규칙을 지원하며 구성 가능성이 매우 높습니다.
• Prettier: 일관된 스타일에 맞춰 코드를 자동으로 포매팅하는 독자적인(opinionated) 코드 포매터입니다. 자바스크립트, 타입스크립트, JSX 및 기타 여러 언어를 지원합니다.
• Husky: Git 훅을 쉽게 관리할 수 있게 해주는 도구입니다. Git 워크플로우의 여러 단계에서 실행될 스크립트를 정의할 수 있습니다.
• lint-staged: 스테이징된 파일에 대해서만 린터와 포매터를 실행하여 프리커밋 프로세스의 속도를 크게 향상시키는 도구입니다. 이를 통해 변경되지 않은 파일에 대한 불필요한 검사를 방지합니다.

프리커밋 훅 구성하기: 단계별 가이드

Husky와 lint-staged를 사용하여 자바스크립트 프로젝트에 프리커밋 훅을 설정하는 방법에 대한 자세한 가이드는 다음과 같습니다:

1단계: 의존성 설치

먼저, npm 또는 yarn을 사용하여 필요한 패키지를 개발 의존성으로 설치합니다:

            npm install --save-dev husky lint-staged eslint prettier
            

              
                Copy
              
            
          

또는 yarn 사용 시:

            yarn add --dev husky lint-staged eslint prettier
            

              
                Copy
              
            
          

2단계: Husky 초기화

Husky는 Git 훅 관리 프로세스를 단순화합니다. 다음 명령을 사용하여 초기화하세요:

            npx husky install
            

              
                Copy
              
            
          

이렇게 하면 프로젝트에 `.husky` 디렉토리가 생성되며, 여기에 Git 훅이 저장됩니다.

3단계: 프리커밋 훅 구성

Husky를 사용하여 프리커밋 훅을 추가합니다:

            npx husky add .husky/pre-commit "npx lint-staged"
            

              
                Copy
              
            
          

이 명령은 `.husky` 디렉토리에 `pre-commit` 파일을 생성하고 여기에 `npx lint-staged` 명령을 추가합니다. 이는 Git에게 각 커밋 전에 lint-staged를 실행하도록 지시합니다.

4단계: lint-staged 구성

lint-staged를 사용하면 스테이징된 파일에 대해서만 린터와 포매터를 실행할 수 있어 프리커밋 프로세스의 속도를 크게 높일 수 있습니다. 프로젝트 루트에 `lint-staged.config.js`(또는 ES 모듈의 경우 `lint-staged.config.mjs`) 파일을 만들고 다음과 같이 구성합니다:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],
};
            

              
                Copy
              
            
          

이 구성은 lint-staged에게 스테이징된 모든 자바스크립트 및 타입스크립트 파일에 대해 ESLint와 Prettier를 실행하도록 지시합니다. ESLint의 `--fix` 플래그는 자동으로 수정할 수 있는 모든 린팅 오류를 수정하고, Prettier의 `--write` 플래그는 파일을 포매팅하고 포매팅된 코드로 덮어씁니다.

또는 `package.json` 파일에 직접 구성을 정의할 수도 있습니다:

            {
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}
            

              
                Copy
              
            
          

5단계: ESLint 구성

아직 프로젝트에 ESLint를 구성하지 않았다면 구성하세요. 다음 명령을 사용하여 ESLint 구성 파일을 생성할 수 있습니다:

            npx eslint --init
            

              
                Copy
              
            
          

이 명령은 프로젝트 요구 사항에 따라 ESLint 구성 파일(`.eslintrc.js`, `.eslintrc.json` 또는 `.eslintrc.yml`)을 만드는 과정을 안내합니다. 다양한 사전 정의된 구성 중에서 선택하거나 자신만의 사용자 지정 규칙을 만들 수 있습니다.

예시 `.eslintrc.js`:

            module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true
    },
    ecmaVersion: 12,
    sourceType: 'module'
  },
  plugins: [
    'react',
    '@typescript-eslint'
  ],
  rules: {
    'no-unused-vars': 'warn',
    'react/prop-types': 'off'
  }
};
            

              
                Copy
              
            
          

이 구성은 권장 ESLint 규칙, 권장 React 규칙, 권장 TypeScript 규칙을 확장하고 Prettier와 통합합니다. 또한 `react/prop-types` 규칙을 비활성화하고 `no-unused-vars` 규칙을 경고로 설정합니다.

6단계: Prettier 구성

프로젝트 루트에 `.prettierrc.js`(또는 `.prettierrc.json`, `.prettierrc.yml`, `.prettierrc.toml`) 파일을 만들어 Prettier를 구성합니다. 프로젝트의 스타일 가이드라인에 맞게 Prettier의 포매팅 옵션을 사용자 정의할 수 있습니다.

예시 `.prettierrc.js`:

            module.exports = {
  semi: false,
  trailingComma: 'all',
  singleQuote: true,
  printWidth: 120,
  tabWidth: 2
};
            

              
                Copy
              
            
          

이 구성은 Prettier가 작은따옴표를 사용하고, 세미콜론을 사용하지 않으며, 후행 쉼표를 사용하고, 출력 너비를 120자로, 탭 너비를 2칸으로 설정하도록 합니다.

또는 `package.json` 내부에 Prettier 구성을 정의할 수 있습니다:

            {
  "prettier": {
    "semi": false,
    "trailingComma": "all",
    "singleQuote": true,
    "printWidth": 120,
    "tabWidth": 2
  }
}
            

              
                Copy
              
            
          

7단계: 구성 테스트하기

구성을 테스트하려면 몇 가지 변경 사항을 스테이징하고 커밋을 시도해 보세요. 예를 들어:

            git add .
            

              
                Copy
              
            
          

            git commit -m "Test pre-commit hook"
            

              
                Copy
              
            
          

린팅이나 포매팅 문제가 있는 경우, ESLint와 Prettier가 자동으로 수정하거나(가능한 경우) 오류를 보고합니다. 오류가 보고되면 커밋이 중단되므로, 다시 커밋하기 전에 문제를 해결할 수 있습니다.

고급 구성 옵션

다른 린터 및 포매터 사용하기

다른 린터와 포매터를 프리커밋 훅 구성에 쉽게 통합할 수 있습니다. 예를 들어, CSS 또는 SASS 파일 린팅에 Stylelint를 사용할 수 있습니다:

            npm install --save-dev stylelint stylelint-config-standard
            

              
                Copy
              
            
          

그런 다음, Stylelint를 포함하도록 `lint-staged.config.js` 파일을 업데이트합니다:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],
  '*.{css,scss}': ['stylelint --fix'],
};
            

              
                Copy
              
            
          

커밋 전 테스트 실행하기

프리커밋 훅의 일부로 단위 테스트를 실행할 수도 있습니다. 이는 코드가 커밋되기 전에 올바르게 작동하는지 확인하는 데 도움이 됩니다. Jest를 사용한다고 가정해 보겠습니다:

            npm install --save-dev jest
            

              
                Copy
              
            
          

테스트 명령을 포함하도록 `lint-staged.config.js` 파일을 업데이트합니다:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write', 'jest --findRelatedTests'],
  '*.{css,scss}': ['stylelint --fix'],
};
            

              
                Copy
              
            
          

`--findRelatedTests` 플래그는 Jest에게 변경된 파일과 관련된 테스트만 실행하도록 지시하여 프로세스 속도를 크게 향상시킵니다.

프리커밋 훅 건너뛰기

경우에 따라 프리커밋 훅을 일시적으로 건너뛰고 싶을 수 있습니다. `git commit` 명령과 함께 `--no-verify` 플래그를 사용하여 이를 수행할 수 있습니다:

            git commit --no-verify -m "Commit message"
            

              
                Copy
              
            
          

그러나 훅은 코드 품질을 유지하는 데 중요한 역할을 하므로 꼭 필요한 경우가 아니면 건너뛰지 않는 것이 일반적으로 권장됩니다.

일반적인 문제 해결

• 훅이 실행되지 않음: Husky가 올바르게 설치 및 초기화되었는지, 그리고 프로젝트 루트에 `.husky` 디렉토리가 있는지 확인하세요. 또한 `.husky` 디렉토리의 `pre-commit` 파일이 실행 가능한지 확인하세요.
• 린팅 오류가 수정되지 않음: ESLint에 `--fix` 플래그가 사용되었는지, 그리고 ESLint 구성이 특정 유형의 오류를 자동으로 수정하도록 설정되어 있는지 확인하세요.
• Prettier가 파일을 포매팅하지 않음: Prettier에 `--write` 플래그가 사용되었는지, 그리고 Prettier 구성이 올바르게 설정되어 있는지 확인하세요.
• 느린 프리커밋 훅: lint-staged를 사용하여 스테이징된 파일에 대해서만 린터와 포매터를 실행하세요. 또한 검사되는 규칙 및 설정 수를 최소화하도록 ESLint 및 Prettier 구성을 최적화하는 것을 고려하세요.
• 충돌하는 구성: ESLint와 Prettier 구성이 서로 충돌하지 않는지 확인하세요. 충돌하는 경우, 충돌을 해결하기 위해 하나 또는 두 구성을 모두 조정해야 할 수 있습니다. 충돌을 피하기 위해 `eslint-config-prettier` 및 `eslint-plugin-prettier`와 같은 공유 구성을 사용하는 것을 고려하세요.

프리커밋 훅 모범 사례

• 훅을 빠르게 유지하세요: 느린 훅은 개발자 생산성에 큰 영향을 미칠 수 있습니다. lint-staged를 사용하여 스테이징된 파일만 처리하고 린터 및 포매터 구성을 최적화하세요.
• 명확한 오류 메시지를 제공하세요: 훅이 실패하면 개발자가 문제를 해결하는 방법을 안내할 수 있도록 명확하고 유익한 오류 메시지를 제공하세요.
• 가능한 한 많이 자동화하세요: 코드 포매팅과 린팅을 자동화하여 수동 작업을 최소화하고 일관성을 보장하세요.
• 팀을 교육하세요: 모든 팀원이 프리커밋 훅의 목적과 이를 효과적으로 사용하는 방법을 이해하도록 하세요.
• 일관된 구성을 사용하세요: 프로젝트 전반에 걸쳐 ESLint, Prettier 및 기타 도구에 대한 일관된 구성을 유지하세요. 이는 모든 코드가 동일한 방식으로 포매팅되고 린팅되도록 보장하는 데 도움이 됩니다. 여러 프로젝트에 걸쳐 쉽게 설치하고 업데이트할 수 있는 공유 구성 패키지를 사용하는 것을 고려하세요.
• 훅을 테스트하세요: 프리커밋 훅이 올바르게 작동하는지, 그리고 예기치 않은 문제를 일으키지 않는지 확인하기 위해 정기적으로 테스트하세요.

전 세계적인 고려 사항

전 세계에 분산된 팀과 협력할 때는 다음 사항을 고려하세요:

• 일관된 도구 버전: 모든 팀원이 동일한 버전의 ESLint, Prettier, Husky, lint-staged를 사용하도록 하세요. 이는 `package.json` 파일에 버전을 명시하고 npm이나 yarn과 같은 패키지 관리자를 사용하여 의존성을 설치함으로써 달성할 수 있습니다.
• 크로스 플랫폼 호환성: 프리커밋 훅이 모든 플랫폼에서 올바르게 작동하는지 확인하기 위해 여러 운영 체제(Windows, macOS, Linux)에서 테스트하세요. 가능하면 크로스 플랫폼 도구와 명령을 사용하세요.
• 시간대 차이: 프리커밋 훅 문제에 대해 팀원들과 소통할 때 시간대 차이를 염두에 두세요. 그들이 문제를 신속하게 해결할 수 있도록 명확한 지침과 예시를 제공하세요.
• 언어 지원: 프로젝트가 여러 언어를 다루는 경우, 프리커밋 훅이 프로젝트에서 사용되는 모든 언어를 지원하는지 확인하세요. 각 언어에 대해 추가적인 린터와 포매터를 설치해야 할 수도 있습니다.

결론

프리커밋 훅을 구현하는 것은 자바스크립트 프로젝트에서 코드 품질을 강제하고, 팀 협업을 개선하며, 유지보수 비용을 줄이는 효과적인 방법입니다. ESLint, Prettier, Husky, lint-staged와 같은 도구를 통합함으로써 코드 포매팅, 린팅, 테스트를 자동화하여 고품질 코드만이 저장소에 커밋되도록 보장할 수 있습니다. 이 가이드에 설명된 단계를 따르면, 더 깨끗하고 유지보수하기 쉬우며 신뢰할 수 있는 자바스크립트 애플리케이션을 구축하는 데 도움이 될 강력한 코드 품질 게이트를 설정할 수 있습니다. 이 관행을 받아들이고 오늘 여러분 팀의 개발 워크플로우를 한 단계 끌어올리세요.